<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Event-driven programming &mdash; The Logtalk Handbook v3.93.0-b01 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
      <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=396eccfe" />

  
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script src="../_static/jquery.js?v=5d32c60e"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
        <script src="../_static/documentation_options.js?v=c8100655"></script>
        <script src="../_static/doctools.js?v=9a2dae69"></script>
        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/js/theme.js"></script>
    <!-- begin favicon -->
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
    <link rel="manifest" href="/site.webmanifest" />
    <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#5bbad5" />
    <meta name="msapplication-TileColor" content="#355b95" />
    <meta name="theme-color" content="#ffffff" />
    <!-- end favicon -->
    
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Multi-threading programming" href="threads.html" />
    <link rel="prev" title="Inheritance" href="inheritance.html" />
   
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            The Logtalk Handbook
              <img src="../_static/logtalk.gif" class="logo" alt="Logo"/>
          </a>
              <div class="version">
                3.93.0
              </div>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
    
              <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="index.html">User Manual</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="declarative.html">Declarative object-oriented programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="features.html">Main features</a></li>
<li class="toctree-l2"><a class="reference internal" href="nomenclature.html">Nomenclature</a></li>
<li class="toctree-l2"><a class="reference internal" href="messages.html">Messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="objects.html">Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="protocols.html">Protocols</a></li>
<li class="toctree-l2"><a class="reference internal" href="categories.html">Categories</a></li>
<li class="toctree-l2"><a class="reference internal" href="predicates.html">Predicates</a></li>
<li class="toctree-l2"><a class="reference internal" href="inheritance.html">Inheritance</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Event-driven programming</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#definitions">Definitions</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#event">Event</a></li>
<li class="toctree-l4"><a class="reference internal" href="#monitor">Monitor</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#event-generation">Event generation</a></li>
<li class="toctree-l3"><a class="reference internal" href="#communicating-events-to-monitors">Communicating events to monitors</a></li>
<li class="toctree-l3"><a class="reference internal" href="#performance-concerns">Performance concerns</a></li>
<li class="toctree-l3"><a class="reference internal" href="#monitor-semantics">Monitor semantics</a></li>
<li class="toctree-l3"><a class="reference internal" href="#activation-order-of-monitors">Activation order of monitors</a></li>
<li class="toctree-l3"><a class="reference internal" href="#event-handling">Event handling</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#defining-new-events">Defining new events</a></li>
<li class="toctree-l4"><a class="reference internal" href="#abolishing-defined-events">Abolishing defined events</a></li>
<li class="toctree-l4"><a class="reference internal" href="#finding-defined-events">Finding defined events</a></li>
<li class="toctree-l4"><a class="reference internal" href="#defining-event-handlers">Defining event handlers</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="threads.html">Multi-threading programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="errors.html">Error handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="reflection.html">Reflection</a></li>
<li class="toctree-l2"><a class="reference internal" href="programming.html">Writing and running applications</a></li>
<li class="toctree-l2"><a class="reference internal" href="printing.html">Printing messages and asking questions</a></li>
<li class="toctree-l2"><a class="reference internal" href="expansion.html">Term and goal expansion</a></li>
<li class="toctree-l2"><a class="reference internal" href="documenting.html">Documenting</a></li>
<li class="toctree-l2"><a class="reference internal" href="debugging.html">Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="performance.html">Performance</a></li>
<li class="toctree-l2"><a class="reference internal" href="installing.html">Installing Logtalk</a></li>
<li class="toctree-l2"><a class="reference internal" href="migration.html">Prolog integration and migration</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../refman/index.html">Reference Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devtools/index.html">Developer Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../libraries/index.html">Libraries</a></li>
<li class="toctree-l1"><a class="reference internal" href="../ports/index.html">Ports</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributions/index.html">Contributions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../bibliography.html">Bibliography</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>

    <p class="caption"><span class="caption-text">External Contents</span></p>
    <ul>
    <li class="toctree-l1"><a class="reference internal" href="../../apis/index.html">APIs</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://logtalk.org">Logtalk website</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://github.com/LogtalkDotOrg/logtalk3">GitHub repo</a></li>
    </ul>
  
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">The Logtalk Handbook</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">User Manual</a></li>
      <li class="breadcrumb-item active">Event-driven programming</li>
      <li class="wy-breadcrumbs-aside">
              <a href="https://github.com/LogtalkDotOrg/logtalk3/blob/master/docs/handbook/sources/userman/events.rst" class="fa fa-github"> Edit on GitHub</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="event-driven-programming">
<span id="events-events"></span><h1>Event-driven programming<a class="headerlink" href="#event-driven-programming" title="Link to this heading"></a></h1>
<p>The addition of event-driven programming capacities to the Logtalk
language <a class="reference internal" href="../bibliography.html#moura94" id="id1"><span>[Moura94]</span></a> is based on a simple but powerful idea:</p>
<blockquote>
<div><p>The computations must result not only from message-sending but also
from the <strong>observation</strong> of message-sending.</p>
</div></blockquote>
<p>The need to associate computations to the occurrence of events was very
early recognized in knowledge representation languages, programming languages
<a class="reference internal" href="../bibliography.html#stefik-et-al-86" id="id2"><span>[Stefik_et_al_86]</span></a>, <a class="reference internal" href="../bibliography.html#moon86" id="id3"><span>[Moon86]</span></a>, operative systems <a class="reference internal" href="../bibliography.html#tanenbaum87" id="id4"><span>[Tanenbaum87]</span></a>, and
graphical user interfaces.</p>
<p>With the integration between object-oriented and event-driven
programming, we intend to achieve the following goals:</p>
<ul class="simple">
<li><p>Minimize the <em>coupling</em> between objects. An object should only contain
what is intrinsic to it. If an object observes another object, that
means that it should depend only on the public protocol of the
object observed and not on the implementation of that protocol.</p></li>
<li><p>Provide a mechanism for building <em>reflexive systems</em> in Logtalk based
on the dynamic behavior of objects in complement to the reflective
information on object predicates and relations.</p></li>
<li><p>Provide a mechanism for easily defining method <em>pre- and
post-conditions</em> that can be toggled using the <a class="reference internal" href="programming.html#flag-events"><span class="std std-ref">events</span></a>
compiler flag. The pre- and post-conditions may be defined in the same
object containing the methods or distributed between several objects
acting as method monitors.</p></li>
<li><p>Provide a <em>publish-subscribe</em> mechanism where public messages play the
role of events.</p></li>
</ul>
<section id="definitions">
<span id="events-definitions"></span><h2>Definitions<a class="headerlink" href="#definitions" title="Link to this heading"></a></h2>
<p>The words <em>event</em> and <em>monitor</em> have multiple meanings in computer
science. To avoid misunderstandings, we start by defining them in
the Logtalk context.</p>
<section id="event">
<span id="events-event"></span><h3>Event<a class="headerlink" href="#event" title="Link to this heading"></a></h3>
<p>In an object-oriented system, all computations start through message
sending. It thus becomes quite natural to declare that the only event
that can occur in this kind of system is precisely the sending of a
message. An event can thus be represented by the ordered tuple
<code class="docutils literal notranslate"><span class="pre">(Object,</span> <span class="pre">Message,</span> <span class="pre">Sender)</span></code>.</p>
<p>If we consider message processing an indivisible activity, we can
interpret the sending of a message and the return of the control to the
object that has sent the message as two distinct events. This
distinction allows us to have more precise control over a system’s
dynamic behavior. In Logtalk, these two types of events have been named
<code class="docutils literal notranslate"><span class="pre">before</span></code> and <code class="docutils literal notranslate"><span class="pre">after</span></code>, respectively for sending a message and for
returning control to the sender. Therefore, we refine our event
representation using the ordered tuple <code class="docutils literal notranslate"><span class="pre">(Event,</span> <span class="pre">Object,</span> <span class="pre">Message,</span> <span class="pre">Sender)</span></code>.</p>
<p>The implementation of events in Logtalk enjoys the following properties:</p>
<dl class="simple">
<dt>Independence between the two types of events</dt><dd><p>We can choose to watch only one event type or to process each one of
the events associated with a message-sending goal in an independent way.</p>
</dd>
<dt>All events are automatically generated by the message-sending mechanism</dt><dd><p>The task of generating events is transparently accomplished
by the message-sending mechanism. The user only needs to define the
events that will be monitored.</p>
</dd>
<dt>The events watched at any moment can be dynamically changed during program execution</dt><dd><p>The notion of event allows the user not only to have the possibility
of observing but also of controlling and modifying an application
behavior, namely by dynamically changing the observed events during
program execution. It is our goal to provide the user with the
possibility of modeling the largest number of situations.</p>
</dd>
</dl>
</section>
<section id="monitor">
<span id="events-monitor"></span><h3>Monitor<a class="headerlink" href="#monitor" title="Link to this heading"></a></h3>
<p>Complementary to the notion of event is the notion of monitor. A monitor
is an object that is automatically notified by the message-sending
mechanism whenever a registered event occurs. Any object that defines
the event-handling predicates can play the role of a monitor.</p>
<p>The implementation of monitors in Logtalk enjoys the following
properties:</p>
<dl class="simple">
<dt>Any object can act as a monitor</dt><dd><p>The monitor status is a role that any object can perform during its
existence. The minimum protocol necessary is declared in the built-in
<a class="reference external" href="../../apis/monitoring_0.html#monitoring-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">monitoring</span></a> protocol. Strictly speaking, the
reference to this protocol is only needed when specializing event handlers.
Nevertheless, it is considered good programming practice to always
refer to the protocol when defining event handlers.</p>
</dd>
<dt>Unlimited number of monitors for each event</dt><dd><p>Several monitors can observe the same event for distinct reasons.
Therefore, the number of monitors per event is bounded only by the
available computing resources.</p>
</dd>
<dt>The monitor status of an object can be dynamically changed at runtime</dt><dd><p>This property does not imply that an object must be dynamic to act as
a monitor (the monitor status of an object is not stored in the
object).</p>
</dd>
<dt>Event handlers cannot modify the event arguments</dt><dd><p>Notably, if the message contains unbound variables, these cannot be
bound by the calls to the monitor event handlers.</p>
</dd>
</dl>
</section>
</section>
<section id="event-generation">
<span id="events-generation"></span><h2>Event generation<a class="headerlink" href="#event-generation" title="Link to this heading"></a></h2>
<p>Assuming that the <a class="reference internal" href="programming.html#flag-events"><span class="std std-ref">events</span></a> flag is set to <code class="docutils literal notranslate"><span class="pre">allow</span></code> for
the object (or category) sending the messages we want to observe, for each
message that is sent using the <a class="reference internal" href="../refman/control/send_to_object_2.html#control-send-to-object-2"><span class="std std-ref">(::)/2</span></a> control
construct, the runtime system automatically generates two events.
The first — <em>before event</em> — is generated when the message is sent. The
second — <em>after event</em> — is generated after the message has successfully
been executed.</p>
<p>Note that <em>self</em> messages (using the <a class="reference internal" href="../refman/control/send_to_self_1.html#control-send-to-self-1"><span class="std std-ref">(::)/1</span></a> control
construct) and <em>super</em> calls (using the <a class="reference internal" href="../refman/control/call_super_1.html#control-call-super-1"><span class="std std-ref">(^^)/1</span></a> control
construct) don’t generate events.</p>
</section>
<section id="communicating-events-to-monitors">
<span id="events-communicating"></span><h2>Communicating events to monitors<a class="headerlink" href="#communicating-events-to-monitors" title="Link to this heading"></a></h2>
<p>Whenever a spied event occurs, the message-sending mechanism calls the
corresponding event handlers directly for all registered monitors. These
calls are internally made, thus bypassing the message-sending primitives
in order to avoid potential endless loops. The event handlers consist of
user definitions for the public predicates declared in the built-in
<a class="reference external" href="../../apis/monitoring_0.html#monitoring-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">monitoring</span></a> protocol (see below for more details).</p>
</section>
<section id="performance-concerns">
<span id="events-performance"></span><h2>Performance concerns<a class="headerlink" href="#performance-concerns" title="Link to this heading"></a></h2>
<p>Ideally, the existence of monitored messages should not affect the
processing of the remaining messages. On the other hand, for each
message that has been sent, the system must verify if its respective
event is monitored. Whenever possible, this verification should be
performed in constant time and independently of the number of monitored
events. The representation of events takes advantage of the first
argument indexing performed by most Prolog compilers, which ensure — in
the general case — access in constant time.</p>
<p>Event support can be turned off on a per-object (or per-category) basis
using the <a class="reference internal" href="programming.html#flag-events"><span class="std std-ref">events</span></a> compiler flag. With event support
turned off, Logtalk uses optimized code for processing message-sending
calls that skips the checking of monitored events, resulting in a small
but measurable performance improvement.</p>
</section>
<section id="monitor-semantics">
<span id="events-semantics"></span><h2>Monitor semantics<a class="headerlink" href="#monitor-semantics" title="Link to this heading"></a></h2>
<p>The established semantics for monitor actions consists of considering
its success as a necessary condition so that a message can succeed:</p>
<ul class="simple">
<li><p>All actions associated with events of type <code class="docutils literal notranslate"><span class="pre">before</span></code> must succeed
so that the message processing can start.</p></li>
<li><p>All actions associated with events of type <code class="docutils literal notranslate"><span class="pre">after</span></code> also have to
succeed so that the message itself succeeds. The failure of any
action associated with an event of type <code class="docutils literal notranslate"><span class="pre">after</span></code> forces backtracking
over the message execution (the failure of a monitor never causes
backtracking over the preceding monitor actions).</p></li>
</ul>
<p>Note that this is the most general choice. If we require a transparent
presence of monitors in a message processing, we just have to define the
monitor actions in such a way that they never fail (which is very simple
to accomplish).</p>
</section>
<section id="activation-order-of-monitors">
<span id="events-order"></span><h2>Activation order of monitors<a class="headerlink" href="#activation-order-of-monitors" title="Link to this heading"></a></h2>
<p>Ideally, whenever there are several monitors defined for the same event,
the calling order should not interfere with the result. However, this is
not always possible. In the case of an event of type <code class="docutils literal notranslate"><span class="pre">before</span></code>, the
failure of a monitor prevents a message from being sent and prevents the
execution of the remaining monitors. In the case of an event of type
<code class="docutils literal notranslate"><span class="pre">after</span></code>, a monitor failure will force backtracking over message
execution. Different orders of monitor activation can therefore lead to
different results if the monitor actions imply object modifications
unrecoverable in case of backtracking. Therefore, the order for monitor
activation should be assumed as arbitrary. In effect, to assume or to
try to impose a specific sequence requires a global knowledge of an
application dynamics, which is not always possible. Furthermore, that
knowledge can reveal itself as incorrect if there is any change in the
execution conditions. Note that, given the independence between
monitors, it does not make sense that a failure forces backtracking over
the actions previously executed.</p>
</section>
<section id="event-handling">
<span id="events-handling"></span><h2>Event handling<a class="headerlink" href="#event-handling" title="Link to this heading"></a></h2>
<p>Logtalk provides three built-in predicates for event handling. These
predicates support defining, enumerating, and abolishing events.
Applications that use events extensively usually define a set of objects
that use these built-in predicates to implement more sophisticated and
higher-level behavior.</p>
<section id="defining-new-events">
<span id="events-defining"></span><h3>Defining new events<a class="headerlink" href="#defining-new-events" title="Link to this heading"></a></h3>
<p>New events can be defined using the <a class="reference internal" href="../refman/predicates/define_events_5.html#predicates-define-events-5"><span class="std std-ref">define_events/5</span></a>
built-in predicate:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- define_events(Event, Object, Message, Sender, Monitor).
</pre></div>
</div>
<p>Note that if any of the <code class="docutils literal notranslate"><span class="pre">Event</span></code>, <code class="docutils literal notranslate"><span class="pre">Object</span></code>, <code class="docutils literal notranslate"><span class="pre">Message</span></code>, and
<code class="docutils literal notranslate"><span class="pre">Sender</span></code> arguments is a free variable or contains free variables, this
call will define a <strong>set</strong> of matching events.</p>
</section>
<section id="abolishing-defined-events">
<span id="events-abolishing"></span><h3>Abolishing defined events<a class="headerlink" href="#abolishing-defined-events" title="Link to this heading"></a></h3>
<p>Events that are no longer needed may be abolished using the
<a class="reference internal" href="../refman/predicates/abolish_events_5.html#predicates-abolish-events-5"><span class="std std-ref">abolish_events/5</span></a> built-in predicate:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- abolish_events(Event, Object, Message, Sender, Monitor).
</pre></div>
</div>
<p>If called with free variables, this goal will remove all matching
events.</p>
</section>
<section id="finding-defined-events">
<span id="events-finding"></span><h3>Finding defined events<a class="headerlink" href="#finding-defined-events" title="Link to this heading"></a></h3>
<p>The events that are currently defined can be retrieved using the
<a class="reference internal" href="../refman/predicates/current_event_5.html#predicates-current-event-5"><span class="std std-ref">current_event/5</span></a> built-in predicate:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- current_event(Event, Object, Message, Sender, Monitor).
</pre></div>
</div>
<p>Note that this predicate will return <strong>sets</strong> of matching events if some
of the returned arguments are free variables or contain free variables.</p>
</section>
<section id="defining-event-handlers">
<span id="events-handlers"></span><h3>Defining event handlers<a class="headerlink" href="#defining-event-handlers" title="Link to this heading"></a></h3>
<p>The <a class="reference external" href="../../apis/monitoring_0.html#monitoring-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">monitoring</span></a> built-in protocol declares two
public predicates, <a class="reference internal" href="../refman/methods/before_3.html#methods-before-3"><span class="std std-ref">before/3</span></a> and <a class="reference internal" href="../refman/methods/after_3.html#methods-after-3"><span class="std std-ref">after/3</span></a>, that
are automatically called to handle <code class="docutils literal notranslate"><span class="pre">before</span></code> and <code class="docutils literal notranslate"><span class="pre">after</span></code> events. Any
object that plays the role of monitor must define one or both of these
event handler methods:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="k">before</span>(<span class="nv">Object</span>, <span class="nv">Message</span>, <span class="nv">Sender</span>) <span class="o">:-</span>
    ... .

<span class="k">after</span>(<span class="nv">Object</span>, <span class="nv">Message</span>, <span class="nv">Sender</span>) <span class="o">:-</span>
    ... .
</pre></div>
</div>
<p>The arguments in both methods are instantiated by the message-sending
mechanism when a monitored event occurs. For example, assume that we
want to define a monitor called <code class="docutils literal notranslate"><span class="pre">tracer</span></code> that will track any message
sent to an object by printing a descriptive text to the standard output.
Its definition could be something like:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(tracer,
    <span class="c">% built-in protocol for event handler methods</span>
    <span class="k">implements</span>(monitoring)).

    <span class="k">before</span>(<span class="nv">Object</span>, <span class="nv">Message</span>, <span class="nv">Sender</span>) <span class="o">:-</span>
        <span class="k">write</span>(<span class="s">&#39;call: &#39;</span>), <span class="k">writeq</span>(<span class="nv">Object</span>),
        <span class="k">write</span>(<span class="s">&#39; &lt;-- &#39;</span>), <span class="k">writeq</span>(<span class="nv">Message</span>),
        <span class="k">write</span>(<span class="s">&#39; from &#39;</span>), <span class="k">writeq</span>(<span class="nv">Sender</span>), <span class="k">nl</span>.

    <span class="k">after</span>(<span class="nv">Object</span>, <span class="nv">Message</span>, <span class="nv">Sender</span>) <span class="o">:-</span>
        <span class="k">write</span>(<span class="s">&#39;exit: &#39;</span>), <span class="k">writeq</span>(<span class="nv">Object</span>),
        <span class="k">write</span>(<span class="s">&#39; &lt;-- &#39;</span>), <span class="k">writeq</span>(<span class="nv">Message</span>),
        <span class="k">write</span>(<span class="s">&#39; from &#39;</span>), <span class="k">writeq</span>(<span class="nv">Sender</span>), <span class="k">nl</span>.

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Assume that we also have the following object:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(any).

<span class="p">    :- </span><span class="k">public</span>(bar<span class="o">/</span><span class="m">1</span>).
    bar(bar).

<span class="p">    :- </span><span class="k">public</span>(foo<span class="o">/</span><span class="m">1</span>).
    foo(foo).

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>After compiling and loading both objects and setting the
<a class="reference internal" href="programming.html#flag-events"><span class="std std-ref">events</span></a> flag to <code class="docutils literal notranslate"><span class="pre">allow</span></code>, we can start tracing
every message sent to any object by calling the
<a class="reference internal" href="../refman/predicates/define_events_5.html#predicates-define-events-5"><span class="std std-ref">define_events/5</span></a> built-in predicate:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- set_logtalk_flag(events, allow).

yes

| ?- define_events(_, _, _, _, tracer).

yes
</pre></div>
</div>
<p>From now on, every message sent from <code class="docutils literal notranslate"><span class="pre">user</span></code> to any object will be
traced to the standard output stream:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- any::bar(X).

call: any &lt;-- bar(X) from user
exit: any &lt;-- bar(bar) from user
X = bar

yes
</pre></div>
</div>
<p>To stop tracing, we can use the <a class="reference internal" href="../refman/predicates/abolish_events_5.html#predicates-abolish-events-5"><span class="std std-ref">abolish_events/5</span></a>
built-in predicate:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- abolish_events(_, _, _, _, tracer).

yes
</pre></div>
</div>
<p>The <a class="reference external" href="../../apis/monitoring_0.html#monitoring-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">monitoring</span></a> protocol declares the event
handlers as public predicates. If necessary, <a class="reference internal" href="protocols.html#protocols-implementing"><span class="std std-ref">protected or private
implementation of the protocol</span></a> may be used in
order to change the scope of the event handler predicates. Note that the
message-sending processing mechanism is able to call the event handlers
irrespective of their scope. Nevertheless, the scope of the event handlers
may be restricted in order to prevent other objects from calling them.</p>
<p>The pseudo-object <a class="reference internal" href="objects.html#objects-user"><span class="std std-ref">user</span></a> can also act as a monitor.
This object expects the <code class="docutils literal notranslate"><span class="pre">before/3</span></code> and <code class="docutils literal notranslate"><span class="pre">after/3</span></code> predicates to be
defined in the plain Prolog database. To avoid predicate existence errors
when setting <code class="docutils literal notranslate"><span class="pre">user</span></code> as a monitor, this object declares the predicates
multifile. Thus, any plain Prolog code defining the predicates should
include the directives:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">multifile</span>(before<span class="o">/</span><span class="m">3</span>).
<span class="p">:- </span><span class="k">multifile</span>(after<span class="o">/</span><span class="m">3</span>).
</pre></div>
</div>
</section>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="inheritance.html" class="btn btn-neutral float-left" title="Inheritance" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="threads.html" class="btn btn-neutral float-right" title="Multi-threading programming" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 1998-2025, Paulo Moura.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>